#ifndef GTRACK_LIST_H__
#define GTRACK_LIST_H__

#include <stdint.h>

/**
* @brief
*   GTrack 链表元素
*
* @details
*   该结构描述了一个列表节点，该节点具有指向列表中上一个和下一个元素的链接。
*/
typedef struct GTrack_ListElem_t
{
    uint32_t                  data;
    struct GTrack_ListElem_t* prev;
    struct GTrack_ListElem_t* next;
} GTrack_ListElem;

/**
* @brief
*   GTrack 链表对象
*
* @details
*   该结构描述了一个列表对象
*/
typedef struct
{
    uint32_t         count;
    GTrack_ListElem* begin;
    GTrack_ListElem* end;
} GTrack_ListObj;

/**
 *  @b Description
 *  @n
 *      该函数用来初始化链表
 *
 *  @param[in]  list
 *      待初始化的链表
 *
 *  @retval
 *      无
 */
void             gtrack_listInit(GTrack_ListObj* list);

/**
 *  @b Description
 *  @n
 *      该函数用来检查链表是否为空
 *
 *  @param[in]  list
 *      待检查链表
 *
 *  @retval
 *      1	-	链表为空
 *  @retval
 *      0	-	链表不为空
 */
int32_t          gtrack_isListEmpty(GTrack_ListObj* list);

/**
 *  @b Description
 *  @n
 *      该函数用来在列表末尾添加一个元素
 *
 *  @param[in]  list
 *      要添加元素的链表
 *  @param[in]  elem
 *      要添加到链表末尾的元素
 *
 *  @retval
 *      无
 */
void             gtrack_listEnqueue(GTrack_ListObj* list, GTrack_ListElem* elem);

/**
 *  @b Description
 *  @n
 *      该函数用来从列表头部取出一个元素
 *
 *  @param[in]  list
 *      要从中删除元素的链表
 *
 *  @retval
 *      链表头（如果列表为空，则为 NULL）
 */
GTrack_ListElem* gtrack_listDequeue(GTrack_ListObj* list);

/**
 *  @b Description
 *  @n
 *      该函数用来获取列表中的第一个元素
 *
 *  @param[in]  list
 *      待获取元素的链表
 *
 *  @retval
 *      第一个元素
 */
GTrack_ListElem* gtrack_listGetFirst(GTrack_ListObj* list);

/**
 *  @b Description
 *  @n
 *      该函数用来获取列表中的下一个元素
 *
 *  @param[in]  elem
 *      待获取元素的链表
 *
 *  @retval
 *      下一个元素
 */
GTrack_ListElem* gtrack_listGetNext(GTrack_ListElem* elem);

/**
 *  @b Description
 *  @n
 *       该函数用来获取列表中元素的个数
 *
 *  @param[in]  list
 *      待获取元素个数的链表
 *
 *  @retval
 *      元素个数
 */
uint32_t         gtrack_listGetCount(GTrack_ListObj* list);

/**
 *  @b Description
 *  @n
 *      该函数用来从列表中删除特定元素
 *
 *  @param[in]  list
 *      要从中删除元素的列表
 *  @param[in]  elem
 *      要删除的元素
 *
 *  @retval
 *      成功     -   0
 *  @retval
 *      错误     -   <0
 */
int32_t          gtrack_listRemoveElement(GTrack_ListObj* list, GTrack_ListElem* elem);

#endif /* GTRACK_LIST_H__ */
